21.17.1 Defining Menus

A keymap acts as a menu if it has an overall prompt string, which is a string that appears as an element of the keymap. (See Format of Keymaps.) The string should describe the purpose of the menu’s commands. Emacs displays the overall prompt string as the menu title in some cases, depending on the toolkit (if any) used for displaying menus.¹² Keyboard menus also display the overall prompt string.

The easiest way to construct a keymap with a prompt string is to specify the string as an argument when you call make-keymap, make-sparse-keymap (see Creating Keymaps), or define-prefix-command (see Definition of define-prefix-command). If you do not want the keymap to operate as a menu, don’t specify a prompt string for it.

Function: keymap-prompt keymap

This function returns the overall prompt string of keymap, or nil if it has none.

The menu’s items are the bindings in the keymap. Each binding associates an event type to a definition, but the event types have no significance for the menu appearance. (Usually we use pseudo-events, symbols that the keyboard cannot generate, as the event types for menu item bindings.) The menu is generated entirely from the bindings that correspond in the keymap to these events.

The order of items in the menu is the same as the order of bindings in the keymap. Since define-key puts new bindings at the front, you should define the menu items starting at the bottom of the menu and moving to the top, if you care about the order. When you add an item to an existing menu, you can specify its position in the menu using define-key-after (see Modifying Menus).